/**
 * FIFS - The Find It File System
 * Copyright (C) 2006 Chris Oklota (chris at oklota dot net)
 * 
 * This program is distributed under the terms of the GNU LGPL.
 * See the file http://www.gnu.org/licenses/lgpl.txt
 */
package fifs;

import java.util.Set;


/**
 * The Data Access Object interface for accessing the backing store for the Find
 * It File System
 */
public interface FifsDao {

    /**
     * Get all tags in the datbase
     * @return The set of tags in the database
     */
    public Set<String> getAllTags();
    
    /**
     * Create the given tag in the database
     * @param tag The tag to create
     * @return true if the tag was created, false otherwise
     */
    public boolean createTag(String tag);
    
    /**
     * Delete the given tag in the database
     * @param tag The tag to delete
     * @return true if the tag was deleted, false otherwise
     */
    public boolean deleteTag(String tag);
    
    /**
     * Create the given file as an empty file in the database.
     * @param file The file info used to create the new file.
     * @return true if the file was created successfully, false otherwise
     */
    public boolean createFile(FifsFile file);
    
    /**
     * Delete the given file from the database.
     * @param file The file info of the file to delete.
     * @return true if the file was deleted successfully, false otherwise
     */
    public boolean deleteFile(FifsFile file);
    
    /**
     * Get all files that are tagged with the given set of tags. If the set
     * of tags is null or contains no tags, then all files in the database
     * should be returned.
     * 
     * @param tags The tags to query on
     * @return The set of files matching the query. If no files match, the set
     * should be empty.
     */
    public Set<FifsFile> getAllFilesByTags(Set<String> tags);

    /**
     * Get the file that's tagged with the given set of tags and
     * with the given filename. The file must contain all tags given,
     * and may also contain more tags.
     * 
     * @param tags The tags of the file to get
     * @param filename The name of the file to get
     * @return The FifsFile requested, or null if it doesn't exist
     */
    public FifsFile getFile(Set<String> tags, String filename);
    
    /**
     * Get the file with the given file handle.
     * 
     * @param fh The file handle to get
     * @return The FifsFile requested, or null if it doesn't exist
     */
    public FifsFile getFile(long fh);
    
    /**
     * Set the given file's size. The file's data should be truncated or
     * null expanded as appropriate.
     * 
     * @param fh The file handle to update
     * @param size The new file size
     * @return true if the file's size was changed, and false otherwise
     */
    public boolean setFileSize(long fh, long size);
    
    /**
     * Update the given file attributes in the database. Only the given
     * files's FuseStat object (retrieved with file.getAttributes()) or
     * its filename may have changed.
     * 
     * @param file The new file info as it should appear in the database
     * @return true if the update worked, false otherwise
     */
    public boolean updateFileAttributes(FifsFile file);
    
    /**
     * Update the given file's tags in the database. Only the given
     * files's tag set (retrieved with file.getTags()) may have
     * changed. Tags may have been removed or added.
     * 
     * @param file The new file info as it should appear in the database
     * @return true if the update worked, false otherwise
     */
    public boolean updateFileTags(FifsFile file);
    
    /**
     * Get the bytes in the given file
     * 
     * @param fh The filehandle to get
     * @param offset The offset within the file to start reading
     * @param length The maximum number of bytes to return in the array
     * @return an array of bytes for the given file handle, or null if
     * it cannot be found. The length of the array should reflect the number
     * of bytes read, not the length requested. An array of length zero
     * indicates end of file.
     */
    public byte[] getFileBytes(long fh, long offset, long length);
    
    /**
     * Write the given bytes into the file at the given offset
     * 
     * @param fh The filehandle to write
     * @param offset The offset within the file to start the write at
     * @param bytes The bytes to write
     * @return true if the write was successful, false otherwise
     */
    public boolean writeFileBytes(long fh, long offset, byte[] bytes);
    
}
